클로드 코드 완벽 가이드 — 10장 커스텀 슬래시 커맨드 사용하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

10장에서 다루는 내용

• 커스텀 슬래시 커맨드 기본기 — 구조, 파라미터, 사용 방법
• 커맨드 스코프 — 프로젝트 커맨드 vs 사용자 커맨드
• 네임스페이싱 — 하위 폴더로 커맨드를 체계적으로 분류

전체 흐름도

[커스텀 슬래시 커맨드란?]
    |
    v
+-------------------------------------+
| 기본 구조                             |
| /<prefix>:<command-name> [arguments] |
|                                       |
| prefix    → 스코프 (project / user)   |
| command   → 마크다운 파일명 (.md 제외)  |
| arguments → 선택적 매개변수            |
+-------------------------------------+
    |
    +--------------------+---------------------+
    |                                          |
    v                                          v
+-------------------------+     +---------------------------+
| 프로젝트 커스텀 커맨드     |     | 사용자 커스텀 커맨드        |
| 위치: .claude/commands/  |     | 위치: ~/.claude/commands/  |
| 접두사: /project:         |     | 접두사: /user:              |
| 팀 공유, CI, 버전 관리     |     | 개인용, 모든 프로젝트 공통   |
+-------------------------+     +---------------------------+
    |                                          |
    +--------------------+---------------------+
                         |
                         v
        +-------------------------------+
        | 네임스페이싱                     |
        | 하위 폴더 = 네임스페이스          |
        | 예: github/create-pr.md        |
        |   → /project:github:create-pr  |
        | 커맨드를 깔끔하게 분류 관리       |
        +-------------------------------+

선수 지식 체크리스트

• [ ] 클로드 코드 기본 슬래시 커맨드 사용법 (/, /help 등)
• [ ] 터미널에서 파일/폴더 생성 및 편집 (mkdir, touch)
• [ ] 마크다운(.md) 파일 작성 기초
• [ ] CLAUDE.md의 역할과 설정 파일 구조 (8~9장)

핵심 키워드

10-1 커스텀 슬래시 커맨드 기본기

한 줄 요약

커스텀 슬래시 커맨드는 자주 쓰는 프롬프트를 마크다운 파일로 저장하고, /로 간편하게 호출하는 기능이다.

쉬운 설명 (전화번호부 비유)

"매번 전화번호를 외워서 눌러야 한다면 불편하다. 자주 거는 번호를 '엄마', '회사'로 저장해두면 이름만 터치하면 된다."

이것이 커스텀 슬래시 커맨드이다: - 커맨드 없이: 매번 긴 프롬프트를 복사-붙여넣기하거나 기억해서 타이핑 - 커맨드 사용: /create-pr처럼 짧은 이름만 입력하면 저장된 프롬프트가 자동 실행

기본 구조

/<prefix>:<command-name> [arguments]

실무 예제

# 1. 커맨드 파일 생성
mkdir -p .claude/commands
cat > .claude/commands/create-pr.md << 'EOF'
이 프로젝트의 변경사항을 분석하고 적절한 PR을 생성해주세요.
- 변경된 파일 목록을 확인
- 커밋 메시지를 기반으로 PR 제목 작성
- 변경 내용을 요약하여 PR 본문 작성
EOF

# 2. 클로드 코드에서 사용
# /project:create-pr issue-79

arguments 활용 포인트: issue-79를 입력하면 클로드 코드가 알아서 이 값을 프롬프트 맥락에서 활용한다. 직접 변수 치환이 아니라 AI가 맥락을 파악하여 사용한다.

핵심 체크포인트

• [ ] 커맨드 파일은 반드시 .md 확장자로 저장
• [ ] 호출할 때는 .md를 제외하고 파일명만 입력
• [ ] arguments는 선택 사항 — 없어도 커맨드 실행 가능
• [ ] 클로드 코드가 arguments를 어떻게 활용할지 스스로 판단

10-2 커스텀 슬래시 커맨드 스코프

한 줄 요약

커맨드를 어디에 저장하느냐에 따라 프로젝트 전용(팀 공유)인지, 개인 범용(모든 프로젝트)인지 결정된다.

쉬운 설명 (회사 vs 개인 문구 비유)

"회사 서랍에 넣으면 팀원 모두가 쓸 수 있고, 집 서랍에 넣으면 나만 어디서든 가져다 쓸 수 있다."

• 프로젝트 커맨드 (회사 서랍): .claude/commands/ → 팀원이 git pull하면 같이 공유
• 사용자 커맨드 (집 서랍): ~/.claude/commands/ → 개인 컴퓨터 어디서든 사용

프로젝트 커스텀 슬래시 커맨드

# 프로젝트 커맨드 예시
.claude/commands/create-pr.md    →  /project:create-pr
.claude/commands/run-tests.md    →  /project:run-tests
.claude/commands/review-code.md  →  /project:review-code

사용자 커스텀 슬래시 커맨드

# 사용자 커맨드 예시
~/.claude/commands/analyze-code.md  →  /user:analyze-code
~/.claude/commands/explain.md       →  /user:explain

잘못된 사용 vs 올바른 사용

❌ 팀 전체가 쓸 CI 실행 커맨드를 ~/.claude/commands/에 저장
   → 다른 팀원은 사용할 수 없음!

✅ 팀 전체가 쓸 CI 실행 커맨드를 .claude/commands/에 저장
   → Git에 포함되어 팀원과 자동 공유

❌ 개인 메모 정리용 커맨드를 .claude/commands/에 저장
   → 팀원에게 불필요한 커맨드가 보임

✅ 개인 메모 정리용 커맨드를 ~/.claude/commands/에 저장
   → 나만 사용, 어떤 프로젝트에서든 호출 가능

핵심 체크포인트

• [ ] 팀 공유 커맨드 → .claude/commands/ (프로젝트 커맨드)
• [ ] 개인 범용 커맨드 → ~/.claude/commands/ (사용자 커맨드)
• [ ] 프로젝트 커맨드는 Git 버전 관리에 포함됨
• [ ] 사용자 커맨드는 한 번 정의하면 모든 프로젝트에서 사용 가능

10-3 네임스페이싱

한 줄 요약

하위 폴더를 만들어 커맨드를 그룹별로 분류하면, 커맨드가 많아져도 체계적으로 관리할 수 있다.

쉬운 설명 (파일 캐비닛 비유)

"서류가 100장인데 전부 한 서랍에 넣으면 찾기 어렵다. 'github 관련', 'test 관련', 'deploy 관련' 폴더를 만들어 분류하면 금방 찾을 수 있다."

• 네임스페이싱 없이: /project:create-pr, /project:run-unit-test, /project:deploy-staging → 이름이 길어지고 구분이 어려움
• 네임스페이싱 적용: /project:github:create-pr, /project:test:unit, /project:deploy:staging → 깔끔하게 분류

네임스페이싱 구조

.claude/commands/
├── github/
│   ├── create-pr.md       →  /project:github:create-pr
│   └── review-pr.md       →  /project:github:review-pr
├── test/
│   ├── unit.md            →  /project:test:unit
│   └── integration.md     →  /project:test:integration
└── deploy/
    └── staging.md         →  /project:deploy:staging

규칙: 하위 폴더명이 곧 네임스페이스가 되고, 콜론(:)으로 구분하여 호출한다.

실무 예제

# 네임스페이싱된 커맨드 생성
mkdir -p .claude/commands/github
cat > .claude/commands/github/create-pr.md << 'EOF'
현재 브랜치의 변경사항을 분석하여 GitHub PR을 생성해주세요.
- 변경 파일 목록 확인
- 커밋 히스토리 분석
- PR 제목과 본문 자동 작성
EOF

# 호출: /project:github:create-pr

핵심 체크포인트

• [ ] 하위 폴더를 만들면 자동으로 네임스페이스가 됨
• [ ] 호출 시 /<prefix>:<namespace>:<command> 형태로 사용
• [ ] 프로젝트 커맨드와 사용자 커맨드 모두 네임스페이싱 가능
• [ ] 관련 커맨드끼리 같은 폴더에 묶으면 관리가 쉬워짐

연습문제

문제 1 (기본)

다음 커맨드 호출이 참조하는 파일의 전체 경로를 적으시오.

/project:github:create-pr

문제 2 (중급)

아래 요구사항을 만족하는 커맨드 파일 구조를 설계하시오.

• 팀 전체가 사용하는 코드 리뷰 커맨드
• 개인만 사용하는 일일 보고서 생성 커맨드
• GitHub 관련 커맨드는 네임스페이싱으로 그룹화

# 팀 공유 (프로젝트 커맨드)
.claude/commands/review-code.md          → /project:review-code
.claude/commands/github/create-pr.md     → /project:github:create-pr
.claude/commands/github/review-pr.md     → /project:github:review-pr

# 개인 전용 (사용자 커맨드)
~/.claude/commands/daily-report.md       → /user:daily-report

문제 3 (심화)

회사에서 다음과 같은 상황이 발생했다. 원인과 해결책을 설명하시오.

"팀원 A가 만든 /project:deploy:staging 커맨드가 팀원 B의 환경에서 보이지 않는다."

부록 A — 용어 사전

부록 B — 비교표

프로젝트 커맨드 vs 사용자 커맨드

커맨드 파일 경로 → 호출 이름 변환 규칙

부록 C — 참고 자료

• 클로드 코드 공식 문서 — Custom Slash Commands
• 클로드 코드 완벽 가이드 GitHub
• 9장 "클로드 코드의 생각 과정 제어하기" — 설정 파일 기초
• 8장 "CLAUDE.md로 클로드 코드 제어하기" — 프로젝트 설정의 기반